<!DOCTYPE HTML>
<html lang="en" class="sidebar-visible no-js">
    <head>
        <!-- Book generated using mdBook -->
        <meta charset="UTF-8">
        <title>final - The `wasm-bindgen` Guide</title>
        <meta content="text/html; charset=utf-8" http-equiv="Content-Type">
        <meta name="description" content="">
        <meta name="viewport" content="width=device-width, initial-scale=1">
        <meta name="theme-color" content="#ffffff" />

        <link rel="shortcut icon" href="../../../favicon.png">
        <link rel="stylesheet" href="../../../css/variables.css">
        <link rel="stylesheet" href="../../../css/general.css">
        <link rel="stylesheet" href="../../../css/chrome.css">
        <link rel="stylesheet" href="../../../css/print.css" media="print">

        <!-- Fonts -->
        <link rel="stylesheet" href="../../../FontAwesome/css/font-awesome.css">
        <link href="https://fonts.googleapis.com/css?family=Open+Sans:300italic,400italic,600italic,700italic,800italic,400,300,600,700,800" rel="stylesheet" type="text/css">
        <link href="https://fonts.googleapis.com/css?family=Source+Code+Pro:500" rel="stylesheet" type="text/css">

        <!-- Highlight.js Stylesheets -->
        <link rel="stylesheet" href="../../../highlight.css">
        <link rel="stylesheet" href="../../../tomorrow-night.css">
        <link rel="stylesheet" href="../../../ayu-highlight.css">

        <!-- Custom theme stylesheets -->
        

        
    </head>
    <body class="light">
        <!-- Provide site root to javascript -->
        <script type="text/javascript">
            var path_to_root = "../../../";
            var default_theme = "light";
        </script>

        <!-- Work around some values being stored in localStorage wrapped in quotes -->
        <script type="text/javascript">
            try {
                var theme = localStorage.getItem('mdbook-theme');
                var sidebar = localStorage.getItem('mdbook-sidebar');

                if (theme.startsWith('"') && theme.endsWith('"')) {
                    localStorage.setItem('mdbook-theme', theme.slice(1, theme.length - 1));
                }

                if (sidebar.startsWith('"') && sidebar.endsWith('"')) {
                    localStorage.setItem('mdbook-sidebar', sidebar.slice(1, sidebar.length - 1));
                }
            } catch (e) { }
        </script>

        <!-- Set the theme before any content is loaded, prevents flash -->
        <script type="text/javascript">
            var theme;
            try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { } 
            if (theme === null || theme === undefined) { theme = default_theme; }
            document.body.className = theme;
            document.querySelector('html').className = theme + ' js';
        </script>

        <!-- Hide / unhide sidebar before it is displayed -->
        <script type="text/javascript">
            var html = document.querySelector('html');
            var sidebar = 'hidden';
            if (document.body.clientWidth >= 1080) {
                try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
                sidebar = sidebar || 'visible';
            }
            html.classList.remove('sidebar-visible');
            html.classList.add("sidebar-" + sidebar);
        </script>

        <nav id="sidebar" class="sidebar" aria-label="Table of contents">
            <ol class="chapter"><li class="affix"><a href="../../../introduction.html">Introduction</a></li><li class="spacer"></li><li><a href="../../../examples/index.html"><strong aria-hidden="true">1.</strong> Examples</a></li><li><ol class="section"><li><a href="../../../examples/hello-world.html"><strong aria-hidden="true">1.1.</strong> Hello, World!</a></li><li><a href="../../../examples/console-log.html"><strong aria-hidden="true">1.2.</strong> Using console.log</a></li><li><a href="../../../examples/add.html"><strong aria-hidden="true">1.3.</strong> Small Wasm files</a></li><li><a href="../../../examples/without-a-bundler.html"><strong aria-hidden="true">1.4.</strong> Without a Bundler</a></li><li><a href="../../../examples/synchronous-instantiation.html"><strong aria-hidden="true">1.5.</strong> Synchronous Instantiation</a></li><li><a href="../../../examples/import-js.html"><strong aria-hidden="true">1.6.</strong> Importing functions from JS</a></li><li><a href="../../../examples/char.html"><strong aria-hidden="true">1.7.</strong> Working with char</a></li><li><a href="../../../examples/wasm-in-wasm.html"><strong aria-hidden="true">1.8.</strong> js-sys: WebAssembly in WebAssembly</a></li><li><a href="../../../examples/dom.html"><strong aria-hidden="true">1.9.</strong> web-sys: DOM hello world</a></li><li><a href="../../../examples/closures.html"><strong aria-hidden="true">1.10.</strong> web-sys: Closures</a></li><li><a href="../../../examples/performance.html"><strong aria-hidden="true">1.11.</strong> web-sys: performance.now</a></li><li><a href="../../../examples/fetch.html"><strong aria-hidden="true">1.12.</strong> web-sys: using fetch</a></li><li><a href="../../../examples/weather_report.html"><strong aria-hidden="true">1.13.</strong> web-sys: Weather report</a></li><li><a href="../../../examples/2d-canvas.html"><strong aria-hidden="true">1.14.</strong> web-sys: canvas hello world</a></li><li><a href="../../../examples/julia.html"><strong aria-hidden="true">1.15.</strong> web-sys: canvas Julia set</a></li><li><a href="../../../examples/web-audio.html"><strong aria-hidden="true">1.16.</strong> web-sys: WebAudio</a></li><li><a href="../../../examples/webgl.html"><strong aria-hidden="true">1.17.</strong> web-sys: WebGL</a></li><li><a href="../../../examples/websockets.html"><strong aria-hidden="true">1.18.</strong> web-sys: WebSockets</a></li><li><a href="../../../examples/webrtc_datachannel.html"><strong aria-hidden="true">1.19.</strong> web-sys: WebRTC DataChannel</a></li><li><a href="../../../examples/request-animation-frame.html"><strong aria-hidden="true">1.20.</strong> web-sys: requestAnimationFrame</a></li><li><a href="../../../examples/paint.html"><strong aria-hidden="true">1.21.</strong> web-sys: A Simple Paint Program</a></li><li><a href="../../../examples/wasm-in-web-worker.html"><strong aria-hidden="true">1.22.</strong> web-sys: Wasm in Web Worker</a></li><li><a href="../../../examples/raytrace.html"><strong aria-hidden="true">1.23.</strong> Parallel Raytracing</a></li><li><a href="../../../examples/wasm-audio-worklet.html"><strong aria-hidden="true">1.24.</strong> Wasm Audio Worklet</a></li><li><a href="../../../examples/todomvc.html"><strong aria-hidden="true">1.25.</strong> web-sys: A TODO MVC App</a></li></ol></li><li><a href="../../../reference/index.html"><strong aria-hidden="true">2.</strong> Reference</a></li><li><ol class="section"><li><a href="../../../reference/deployment.html"><strong aria-hidden="true">2.1.</strong> Deployment</a></li><li><a href="../../../reference/js-snippets.html"><strong aria-hidden="true">2.2.</strong> JS snippets</a></li><li><a href="../../../reference/static-js-objects.html"><strong aria-hidden="true">2.3.</strong> Static JS Objects</a></li><li><a href="../../../reference/passing-rust-closures-to-js.html"><strong aria-hidden="true">2.4.</strong> Passing Rust Closures to JS</a></li><li><a href="../../../reference/receiving-js-closures-in-rust.html"><strong aria-hidden="true">2.5.</strong> Receiving JS Closures in Rust</a></li><li><a href="../../../reference/js-promises-and-rust-futures.html"><strong aria-hidden="true">2.6.</strong> Promises and Futures</a></li><li><a href="../../../reference/iterating-over-js-values.html"><strong aria-hidden="true">2.7.</strong> Iterating over JS Values</a></li><li><a href="../../../reference/arbitrary-data-with-serde.html"><strong aria-hidden="true">2.8.</strong> Arbitrary Data with Serde</a></li><li><a href="../../../reference/accessing-properties-of-untyped-js-values.html"><strong aria-hidden="true">2.9.</strong> Accessing Properties of Untyped JS Values</a></li><li><a href="../../../reference/working-with-duck-typed-interfaces.html"><strong aria-hidden="true">2.10.</strong> Working with Duck-Typed Interfaces</a></li><li><a href="../../../reference/cli.html"><strong aria-hidden="true">2.11.</strong> Command Line Interface</a></li><li><a href="../../../reference/optimize-size.html"><strong aria-hidden="true">2.12.</strong> Optimizing for Size</a></li><li><a href="../../../reference/rust-targets.html"><strong aria-hidden="true">2.13.</strong> Supported Rust Targets</a></li><li><a href="../../../reference/browser-support.html"><strong aria-hidden="true">2.14.</strong> Supported Browsers</a></li><li><a href="../../../reference/weak-references.html"><strong aria-hidden="true">2.15.</strong> Support for Weak References</a></li><li><a href="../../../reference/reference-types.html"><strong aria-hidden="true">2.16.</strong> Support for Reference Types</a></li><li><a href="../../../reference/types.html"><strong aria-hidden="true">2.17.</strong> Supported Types</a></li><li><ol class="section"><li><a href="../../../reference/types/imported-js-types.html"><strong aria-hidden="true">2.17.1.</strong> Imported JavaScript Types</a></li><li><a href="../../../reference/types/exported-rust-types.html"><strong aria-hidden="true">2.17.2.</strong> Exported Rust Types</a></li><li><a href="../../../reference/types/jsvalue.html"><strong aria-hidden="true">2.17.3.</strong> JsValue</a></li><li><a href="../../../reference/types/boxed-slices.html"><strong aria-hidden="true">2.17.4.</strong> Box&lt;[T]&gt; and Vec<T></a></li><li><a href="../../../reference/types/pointers.html"><strong aria-hidden="true">2.17.5.</strong> *const T and *mut T</a></li><li><a href="../../../reference/types/non-null.html"><strong aria-hidden="true">2.17.6.</strong> NonNull<T></a></li><li><a href="../../../reference/types/numbers.html"><strong aria-hidden="true">2.17.7.</strong> Numbers</a></li><li><a href="../../../reference/types/bool.html"><strong aria-hidden="true">2.17.8.</strong> bool</a></li><li><a href="../../../reference/types/char.html"><strong aria-hidden="true">2.17.9.</strong> char</a></li><li><a href="../../../reference/types/str.html"><strong aria-hidden="true">2.17.10.</strong> str</a></li><li><a href="../../../reference/types/string.html"><strong aria-hidden="true">2.17.11.</strong> String</a></li><li><a href="../../../reference/types/number-slices.html"><strong aria-hidden="true">2.17.12.</strong> Number Slices</a></li><li><a href="../../../reference/types/boxed-number-slices.html"><strong aria-hidden="true">2.17.13.</strong> Boxed Number Slices</a></li><li><a href="../../../reference/types/result.html"><strong aria-hidden="true">2.17.14.</strong> Result&lt;T, E&gt;</a></li></ol></li><li><a href="../../../reference/attributes/index.html"><strong aria-hidden="true">2.18.</strong> #[wasm_bindgen] Attributes</a></li><li><ol class="section"><li><a href="../../../reference/attributes/on-js-imports/index.html"><strong aria-hidden="true">2.18.1.</strong> On JavaScript Imports</a></li><li><ol class="section"><li><a href="../../../reference/attributes/on-js-imports/catch.html"><strong aria-hidden="true">2.18.1.1.</strong> catch</a></li><li><a href="../../../reference/attributes/on-js-imports/constructor.html"><strong aria-hidden="true">2.18.1.2.</strong> constructor</a></li><li><a href="../../../reference/attributes/on-js-imports/extends.html"><strong aria-hidden="true">2.18.1.3.</strong> extends</a></li><li><a href="../../../reference/attributes/on-js-imports/getter-and-setter.html"><strong aria-hidden="true">2.18.1.4.</strong> getter and setter</a></li><li><a href="../../../reference/attributes/on-js-imports/final.html" class="active"><strong aria-hidden="true">2.18.1.5.</strong> final</a></li><li><a href="../../../reference/attributes/on-js-imports/indexing-getter-setter-deleter.html"><strong aria-hidden="true">2.18.1.6.</strong> indexing_getter, indexing_setter, and indexing_deleter</a></li><li><a href="../../../reference/attributes/on-js-imports/js_class.html"><strong aria-hidden="true">2.18.1.7.</strong> js_class = &quot;Blah&quot;</a></li><li><a href="../../../reference/attributes/on-js-imports/js_name.html"><strong aria-hidden="true">2.18.1.8.</strong> js_name</a></li><li><a href="../../../reference/attributes/on-js-imports/js_namespace.html"><strong aria-hidden="true">2.18.1.9.</strong> js_namespace</a></li><li><a href="../../../reference/attributes/on-js-imports/method.html"><strong aria-hidden="true">2.18.1.10.</strong> method</a></li><li><a href="../../../reference/attributes/on-js-imports/module.html"><strong aria-hidden="true">2.18.1.11.</strong> module = &quot;blah&quot;</a></li><li><a href="../../../reference/attributes/on-js-imports/raw_module.html"><strong aria-hidden="true">2.18.1.12.</strong> raw_module = &quot;blah&quot;</a></li><li><a href="../../../reference/attributes/on-js-imports/no_deref.html"><strong aria-hidden="true">2.18.1.13.</strong> no_deref</a></li><li><a href="../../../reference/attributes/on-js-imports/static_method_of.html"><strong aria-hidden="true">2.18.1.14.</strong> static_method_of = Blah</a></li><li><a href="../../../reference/attributes/on-js-imports/structural.html"><strong aria-hidden="true">2.18.1.15.</strong> structural</a></li><li><a href="../../../reference/attributes/on-js-imports/typescript_type.html"><strong aria-hidden="true">2.18.1.16.</strong> typescript_type</a></li><li><a href="../../../reference/attributes/on-js-imports/variadic.html"><strong aria-hidden="true">2.18.1.17.</strong> variadic</a></li><li><a href="../../../reference/attributes/on-js-imports/vendor_prefix.html"><strong aria-hidden="true">2.18.1.18.</strong> vendor_prefix</a></li></ol></li><li><a href="../../../reference/attributes/on-rust-exports/index.html"><strong aria-hidden="true">2.18.2.</strong> On Rust Exports</a></li><li><ol class="section"><li><a href="../../../reference/attributes/on-rust-exports/constructor.html"><strong aria-hidden="true">2.18.2.1.</strong> constructor</a></li><li><a href="../../../reference/attributes/on-rust-exports/js_name.html"><strong aria-hidden="true">2.18.2.2.</strong> js_name = Blah</a></li><li><a href="../../../reference/attributes/on-rust-exports/js_class.html"><strong aria-hidden="true">2.18.2.3.</strong> js_class = Blah</a></li><li><a href="../../../reference/attributes/on-rust-exports/readonly.html"><strong aria-hidden="true">2.18.2.4.</strong> readonly</a></li><li><a href="../../../reference/attributes/on-rust-exports/skip.html"><strong aria-hidden="true">2.18.2.5.</strong> skip</a></li><li><a href="../../../reference/attributes/on-rust-exports/skip_jsdoc.html"><strong aria-hidden="true">2.18.2.6.</strong> skip_jsdoc</a></li><li><a href="../../../reference/attributes/on-rust-exports/start.html"><strong aria-hidden="true">2.18.2.7.</strong> start</a></li><li><a href="../../../reference/attributes/on-rust-exports/main.html"><strong aria-hidden="true">2.18.2.8.</strong> main</a></li><li><a href="../../../reference/attributes/on-rust-exports/typescript_custom_section.html"><strong aria-hidden="true">2.18.2.9.</strong> typescript_custom_section</a></li><li><a href="../../../reference/attributes/on-rust-exports/getter-and-setter.html"><strong aria-hidden="true">2.18.2.10.</strong> getter and setter</a></li><li><a href="../../../reference/attributes/on-rust-exports/inspectable.html"><strong aria-hidden="true">2.18.2.11.</strong> inspectable</a></li><li><a href="../../../reference/attributes/on-rust-exports/skip_typescript.html"><strong aria-hidden="true">2.18.2.12.</strong> skip_typescript</a></li><li><a href="../../../reference/attributes/on-rust-exports/getter_with_clone.html"><strong aria-hidden="true">2.18.2.13.</strong> getter_with_clone</a></li><li><a href="../../../reference/attributes/on-rust-exports/unchecked_type.html"><strong aria-hidden="true">2.18.2.14.</strong> unchecked_return_type and unchecked_param_type</a></li><li><a href="../../../reference/attributes/on-rust-exports/description.html"><strong aria-hidden="true">2.18.2.15.</strong> return_description and param_description</a></li></ol></li></ol></li></ol></li><li><a href="../../../web-sys/index.html"><strong aria-hidden="true">3.</strong> web-sys</a></li><li><ol class="section"><li><a href="../../../web-sys/using-web-sys.html"><strong aria-hidden="true">3.1.</strong> Using web-sys</a></li><li><a href="../../../web-sys/cargo-features.html"><strong aria-hidden="true">3.2.</strong> Cargo Features</a></li><li><a href="../../../web-sys/function-overloads.html"><strong aria-hidden="true">3.3.</strong> Function Overloads</a></li><li><a href="../../../web-sys/type-translations.html"><strong aria-hidden="true">3.4.</strong> Type Translations</a></li><li><a href="../../../web-sys/inheritance.html"><strong aria-hidden="true">3.5.</strong> Inheritance</a></li><li><a href="../../../web-sys/unstable-apis.html"><strong aria-hidden="true">3.6.</strong> Unstable APIs</a></li></ol></li><li><a href="../../../wasm-bindgen-test/index.html"><strong aria-hidden="true">4.</strong> Testing with wasm-bindgen-test</a></li><li><ol class="section"><li><a href="../../../wasm-bindgen-test/usage.html"><strong aria-hidden="true">4.1.</strong> Usage</a></li><li><a href="../../../wasm-bindgen-test/asynchronous-tests.html"><strong aria-hidden="true">4.2.</strong> Writing Asynchronous Tests</a></li><li><a href="../../../wasm-bindgen-test/browsers.html"><strong aria-hidden="true">4.3.</strong> Testing in Headless Browsers</a></li><li><a href="../../../wasm-bindgen-test/continuous-integration.html"><strong aria-hidden="true">4.4.</strong> Continuous Integration</a></li><li><a href="../../../wasm-bindgen-test/coverage.html"><strong aria-hidden="true">4.5.</strong> Coverage (Experimental)</a></li></ol></li><li><a href="../../../contributing/index.html"><strong aria-hidden="true">5.</strong> Contributing to wasm-bindgen</a></li><li><ol class="section"><li><a href="../../../contributing/testing.html"><strong aria-hidden="true">5.1.</strong> Testing</a></li><li><a href="../../../contributing/design/index.html"><strong aria-hidden="true">5.2.</strong> Internal Design</a></li><li><ol class="section"><li><a href="../../../contributing/design/js-objects-in-rust.html"><strong aria-hidden="true">5.2.1.</strong> JS Objects in Rust</a></li><li><a href="../../../contributing/design/exporting-rust.html"><strong aria-hidden="true">5.2.2.</strong> Exporting a function to JS</a></li><li><a href="../../../contributing/design/exporting-rust-struct.html"><strong aria-hidden="true">5.2.3.</strong> Exporting a struct to JS</a></li><li><a href="../../../contributing/design/importing-js.html"><strong aria-hidden="true">5.2.4.</strong> Importing a function from JS</a></li><li><a href="../../../contributing/design/importing-js-struct.html"><strong aria-hidden="true">5.2.5.</strong> Importing a class from JS</a></li><li><a href="../../../contributing/design/rust-type-conversions.html"><strong aria-hidden="true">5.2.6.</strong> Rust Type conversions</a></li><li><a href="../../../contributing/design/describe.html"><strong aria-hidden="true">5.2.7.</strong> Types in wasm-bindgen</a></li></ol></li><li><a href="../../../contributing/js-sys/index.html"><strong aria-hidden="true">5.3.</strong> js-sys</a></li><li><ol class="section"><li><a href="../../../contributing/js-sys/testing.html"><strong aria-hidden="true">5.3.1.</strong> Testing</a></li><li><a href="../../../contributing/js-sys/adding-more-apis.html"><strong aria-hidden="true">5.3.2.</strong> Adding More APIs</a></li></ol></li><li><a href="../../../contributing/web-sys/index.html"><strong aria-hidden="true">5.4.</strong> web-sys</a></li><li><ol class="section"><li><a href="../../../contributing/web-sys/overview.html"><strong aria-hidden="true">5.4.1.</strong> Overview</a></li><li><a href="../../../contributing/web-sys/testing.html"><strong aria-hidden="true">5.4.2.</strong> Testing</a></li><li><a href="../../../contributing/web-sys/logging.html"><strong aria-hidden="true">5.4.3.</strong> Logging</a></li><li><a href="../../../contributing/web-sys/supporting-more-web-apis.html"><strong aria-hidden="true">5.4.4.</strong> Supporting More Web APIs</a></li></ol></li><li><a href="../../../contributing/publishing.html"><strong aria-hidden="true">5.5.</strong> Publishing</a></li><li><a href="../../../contributing/team.html"><strong aria-hidden="true">5.6.</strong> Team</a></li></ol></li></ol>
        </nav>

        <div id="page-wrapper" class="page-wrapper">

            <div class="page">
                <style>
  header.warning {
    background-color: rgb(242, 222, 222);
    border-bottom-color: rgb(238, 211, 215);
    border-bottom-left-radius: 4px;
    border-bottom-right-radius: 4px;
    border-bottom-style: solid;
    border-bottom-width: 0.666667px;
    border-image-outset: 0 0 0 0;
    border-image-repeat: stretch stretch;
    border-image-slice: 100% 100% 100% 100%;
    border-image-source: none;
    border-image-width: 1 1 1 1;
    border-left-color: rgb(238, 211, 215);
    border-left-style: solid;
    border-left-width: 0.666667px;
    border-right-color: rgb(238, 211, 215);
    border-right-style: solid;
    border-right-width: 0.666667px;
    border-top-color: rgb(238, 211, 215);
    border-top-left-radius: 4px;
    border-top-right-radius: 4px;
    border-top-style: solid;
    border-top-width: 0.666667px;
    color: rgb(185, 74, 72);
    margin-bottom: 0px;
    margin-left: 0px;
    margin-right: 0px;
    margin-top: 30px;
    padding-bottom: 8px;
    padding-left: 14px;
    padding-right: 35px;
    padding-top: 8px;
    text-align: center;
  }
</style>
<header class='warning'>
  This documentation is
  <a
  href="https://blog.rust-lang.org/inside-rust/2025/07/21/sunsetting-the-rustwasm-github-org/">no
  longer maintained at this domain</a>, and is now maintained
  <a href="https://wasm-bindgen.github.io/wasm-bindgen/">
  at wasm-bindgen.github.io</a> instead.
</header>

                <div id="menu-bar" class="menu-bar">
                    <div id="menu-bar-sticky-container">
                        <div class="left-buttons">
                            <button id="sidebar-toggle" class="icon-button" type="button" title="Toggle Table of Contents" aria-label="Toggle Table of Contents" aria-controls="sidebar">
                                <i class="fa fa-bars"></i>
                            </button>
                            <button id="theme-toggle" class="icon-button" type="button" title="Change theme" aria-label="Change theme" aria-haspopup="true" aria-expanded="false" aria-controls="theme-list">
                                <i class="fa fa-paint-brush"></i>
                            </button>
                            <ul id="theme-list" class="theme-popup" aria-label="Themes" role="menu">
                                <li role="none"><button role="menuitem" class="theme" id="light">Light (default)</button></li>
                                <li role="none"><button role="menuitem" class="theme" id="rust">Rust</button></li>
                                <li role="none"><button role="menuitem" class="theme" id="coal">Coal</button></li>
                                <li role="none"><button role="menuitem" class="theme" id="navy">Navy</button></li>
                                <li role="none"><button role="menuitem" class="theme" id="ayu">Ayu</button></li>
                            </ul>
                            
                        </div>

                        <h1 class="menu-title">The `wasm-bindgen` Guide</h1> 

                        <div class="right-buttons">
                            <a href="../../../print.html" title="Print this book" aria-label="Print this book">
                                <i id="print-button" class="fa fa-print"></i>
                            </a>
                            
                        </div>
                    </div>
                </div>

                

                <!-- Apply ARIA attributes after the sidebar and the sidebar toggle button are added to the DOM -->
                <script type="text/javascript">
                    document.getElementById('sidebar-toggle').setAttribute('aria-expanded', sidebar === 'visible');
                    document.getElementById('sidebar').setAttribute('aria-hidden', sidebar !== 'visible');
                    Array.from(document.querySelectorAll('#sidebar a')).forEach(function(link) {
                        link.setAttribute('tabIndex', sidebar === 'visible' ? 0 : -1);
                    });
                </script>

                <div id="content" class="content">
                    <main>
                        <a class="header" href="#final" id="final"><h1><code>final</code></h1></a>
<p>The <code>final</code> attribute is the converse of the <a href="structural.html"><code>structural</code>
attribute</a>. It configures how <code>wasm-bindgen</code> will generate JS
imports to call the imported function. Notably a function imported by <code>final</code>
never changes after it was imported, whereas a function imported by default (or
with <code>structural</code>) is subject to runtime lookup rules such as walking the
prototype chain of an object. Note that <code>final</code> is not suitable for accessing
data descriptor properties of JS objects; to accomplish this, use the <code>structural</code>
attribute.</p>
<p>The <code>final</code> attribute is intended to be purely related to performance. It
ideally has no user-visible effect, and <code>structural</code> imports (the default)
should be able to transparently switch to <code>final</code> eventually.</p>
<p>The eventual performance aspect is that with the <a href="https://github.com/WebAssembly/component-model">component model
proposal</a> then <code>wasm-bindgen</code> will need to generate far fewer JS
function shims to import than it does today. For example, consider this import
today:</p>
<pre><pre class="playpen"><code class="language-rust">
# #![allow(unused_variables)]
#fn main() {
#[wasm_bindgen]
extern &quot;C&quot; {
    type Foo;
    #[wasm_bindgen(method)]
    fn bar(this: &amp;Foo, argument: &amp;str) -&gt; JsValue;
}
#}</code></pre></pre>
<p><strong>Without the <code>final</code> attribute</strong> the generated JS looks like this:</p>
<pre><code class="language-js">// without `final`
export function __wbg_bar_a81456386e6b526f(arg0, arg1, arg2) {
    let varg1 = getStringFromWasm(arg1, arg2);
    return addHeapObject(getObject(arg0).bar(varg1));
}
</code></pre>
<p>We can see here that this JS function shim is required, but it's all relatively
self-contained. It does, however, execute the <code>bar</code> method in a duck-type-y
fashion in the sense that it never validates <code>getObject(arg0)</code> is of type <code>Foo</code>
to actually call the <code>Foo.prototype.bar</code> method.</p>
<p>If we instead, however, write this:</p>
<pre><pre class="playpen"><code class="language-rust">
# #![allow(unused_variables)]
#fn main() {
#[wasm_bindgen]
extern &quot;C&quot; {
    type Foo;
    #[wasm_bindgen(method, final)] // note the change here
    fn bar(this: &amp;Foo, argument: &amp;str) -&gt; JsValue;
}
#}</code></pre></pre>
<p>it generates this JS glue (roughly):</p>
<pre><code class="language-js">const __wbg_bar_target = Foo.prototype.bar;

export function __wbg_bar_a81456386e6b526f(arg0, arg1, arg2) {
    let varg1 = getStringFromWasm(arg1, arg2);
    return addHeapObject(__wbg_bar_target.call(getObject(arg0), varg1));
}
</code></pre>
<p>The difference here is pretty subtle, but we can see how the function being
called is hoisted out of the generated shim and is bound to always be
<code>Foo.prototype.bar</code>. This then uses the <code>Function.call</code> method to invoke that
function with <code>getObject(arg0)</code> as the receiver.</p>
<p>But wait, there's still a JS function shim here even with <code>final</code>! That's true,
and this is simply a fact of future WebAssembly proposals not being implemented
yet. The semantics, though, match the future <a href="https://github.com/WebAssembly/component-model">component model
proposal</a> because the method being called is determined exactly
once, and it's located on the prototype chain rather than being resolved at
runtime when the function is called.</p>
<a class="header" href="#interaction-with-future-proposals" id="interaction-with-future-proposals"><h2>Interaction with future proposals</h2></a>
<p>If you're curious to see how our JS function shim will be eliminated entirely,
let's take a look at the generated bindings. We're starting off with this:</p>
<pre><code class="language-js">const __wbg_bar_target = Foo.prototype.bar;

export function __wbg_bar_a81456386e6b526f(arg0, arg1, arg2) {
    let varg1 = getStringFromWasm(arg1, arg2);
    return addHeapObject(__wbg_bar_target.call(getObject(arg0), varg1));
}
</code></pre>
<p>... and once the <a href="https://github.com/WebAssembly/reference-types">reference types proposal</a> is implemented then
we won't need some of these pesky functions. That'll transform our generated JS
shim to look like:</p>
<pre><code class="language-js">const __wbg_bar_target = Foo.prototype.bar;

export function __wbg_bar_a81456386e6b526f(arg0, arg1, arg2) {
    let varg1 = getStringFromWasm(arg1, arg2);
    return __wbg_bar_target.call(arg0, varg1);
}
</code></pre>
<p>Getting better! Next up we need the component model proposal. Note that the
proposal is undergoing some changes right now so it's tough to link to reference
documentation, but it suffices to say that it'll empower us with at least two
different features.</p>
<p>First, component model promises to provide the concept of &quot;argument conversions&quot;.
The <code>arg1</code> and <code>arg2</code> values here are actually a pointer and a length to a utf-8
encoded string, and with component model we'll be able to annotate that this
import should take those two arguments and convert them to a JS string (that is,
the <em>host</em> should do this, the WebAssembly engine). Using that feature we can
further trim this down to:</p>
<pre><code class="language-js">const __wbg_bar_target = Foo.prototype.bar;

export function __wbg_bar_a81456386e6b526f(arg0, varg1) {
    return __wbg_bar_target.call(arg0, varg1);
}
</code></pre>
<p>And finally, the second promise of the component model proposal is that we can
flag a function call to indicate the first argument is the <code>this</code> binding of the
function call. Today the <code>this</code> value of all called imported functions is
<code>undefined</code>, and this flag (configured with component model) will indicate the
first argument here is actually the <code>this</code>.</p>
<p>With that in mind we can further transform this to:</p>
<pre><code class="language-js">export const __wbg_bar_a81456386e6b526f = Foo.prototype.bar;
</code></pre>
<p>and voila! We, with <a href="https://github.com/WebAssembly/reference-types">reference types</a> and <a href="https://github.com/WebAssembly/component-model">component
model</a>, now have no JS function shim at all necessary to call
the imported function. Additionally future Wasm proposals to the ES module
system may also mean that don't even need the <code>export const ...</code> here too.</p>
<p>It's also worth pointing out that with all these Wasm proposals implemented the
default way to import the <code>bar</code> function (aka <code>structural</code>) would generate a JS
function shim that looks like:</p>
<pre><code class="language-js">export function __wbg_bar_a81456386e6b526f(varg1) {
    return this.bar(varg1);
}
</code></pre>
<p>where this import is still subject to runtime prototype chain lookups and such.</p>

                    </main>

                    <nav class="nav-wrapper" aria-label="Page navigation">
                        <!-- Mobile navigation buttons -->
                        
                            <a rel="prev" href="../../../reference/attributes/on-js-imports/getter-and-setter.html" class="mobile-nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
                                <i class="fa fa-angle-left"></i>
                            </a>
                        

                        
                            <a rel="next" href="../../../reference/attributes/on-js-imports/indexing-getter-setter-deleter.html" class="mobile-nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
                                <i class="fa fa-angle-right"></i>
                            </a>
                        

                        <div style="clear: both"></div>
                    </nav>
                </div>
            </div>

            <nav class="nav-wide-wrapper" aria-label="Page navigation">
                
                    <a href="../../../reference/attributes/on-js-imports/getter-and-setter.html" class="nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
                        <i class="fa fa-angle-left"></i>
                    </a>
                

                
                    <a href="../../../reference/attributes/on-js-imports/indexing-getter-setter-deleter.html" class="nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
                        <i class="fa fa-angle-right"></i>
                    </a>
                
            </nav>

        </div>

        

        

        

        

        <script src="../../../clipboard.min.js" type="text/javascript" charset="utf-8"></script>
        <script src="../../../highlight.js" type="text/javascript" charset="utf-8"></script>
        <script src="../../../book.js" type="text/javascript" charset="utf-8"></script>

        <!-- Custom JS scripts -->
        

        

    </body>
</html>
